home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / gui / bgui11b.lha / ARexxClass / arexxclass.doc < prev    next >
Encoding:
Text File  |  1994-09-26  |  10.8 KB  |  274 lines
  1.  
  2.            $RCSfile: arexxclass.doc,v $
  3.         Description: ARexxClass documentation.
  4.           Copyright: (C) Copyright 1994 Jaba Development.
  5.                      (C) Copyright 1994 Jan van den Baard.
  6.                      All Rights Reserved.
  7.  
  8.             $Author: jaba $
  9.           $Revision: 1.1 $
  10.               $Date: 1994/09/18 12:21:05 $
  11. ------------------------------------------------------------------------------
  12.  
  13. TABLE OF CONTENTS
  14.  
  15. arexxclass/--background--
  16. arexxclass/Methods
  17. arexxclass/Attributes
  18.  
  19. arexxclass/--background--                            arexxclass/--background--
  20.  
  21.     NAME
  22.         Class:          arexxclass
  23.         Superclass:     ROOTCLASS
  24.         Include File    "ARexxClass.h"
  25.  
  26.     FUNCTION
  27.         To provide you with a very easy way to implement an ARexx host in your
  28.         programs.  The  class  will  take over all the grunt work for you like
  29.         host setup, message handling, argument parsing and so on. All you have
  30.         to do is to create an object from  this class  and  write  the command
  31.         code.
  32.  
  33.     NOTE
  34.         This class  is  provided as source code and two linkable ".o" modules.
  35.         To make  use  of  this class you should link with the  supplied object
  36.         code or,  if  your  compiler  does  not  like these object modules,  a
  37.         re-compiled version of the source.
  38.  
  39.         Also your program must open the following libraries:
  40.  
  41.         intuition.library       - V37 or better.
  42.         utility.library         - V37 or better.
  43.         rexxsyslib.library      - V36 or better.
  44.         dos.library             - V37 or better.
  45.  
  46.         Ofcourse these libraries must remain open until you are done using the
  47.         class.
  48.  
  49.         There are two linkable object modules supplied both compiled with DICE
  50.         v3.0. "arexxclass.o"  is  an  object  module  which uses normal system
  51.         memory allocation/deallocation routines. "arexxclass_p.o" is an object
  52.         module which uses memory pools for it's allocations. You will need the
  53.         3.1 amiga.lib  to  link with the later. Both modules are compiled with
  54.         registered args turned off.
  55.  
  56.         The source  of  this  class  is based on the source output of ARexxBox
  57.         V1.12 by Michael Baltzer.
  58.  
  59. arexxclass/Methods                                          arexxclass/Methods
  60.  
  61.     NEW METHODS
  62.         ACM_HANDLE_EVENT -- This method will handle all incoming  and outgoing
  63.                 message traffic from your host.   When  you are  signalled you
  64.                 simply call this method and everything is done for you.
  65.  
  66.                 No return code is specified for this method.
  67.  
  68.         ACM_EXECUTE -- This method allows you to  execute one of  the commands
  69.                 from your host. Any unknown command is shipped of to the ARexx
  70.                 server.    This  method  uses  the  following  custom  message
  71.                 structure:
  72.  
  73.                 struct acmExecute {
  74.                         ULONG           MethodID;       /* ACM_EXECUTE */
  75.                         UBYTE          *acme_CommandString;
  76.                         LONG           *acme_RC;
  77.                         LONG           *acme_RC2;
  78.                         UBYTE          *acme_Result;
  79.                         BPTR            acme_IO;
  80.                 };
  81.  
  82.                 acme_CommandString -- This must point to the command including
  83.                         arguments to execute.   If the command is found in the
  84.                         host  command  list  it  will  be  executed.   Unknown
  85.                         commands will be shipped off to the ARexx server.
  86.  
  87.                 acme_RC, acme_RC2, acme_Result --  If  you  wish to  know what
  88.                         errors occured during the execution of the command you
  89.                         may provide storage pointers here.  After  the command
  90.                         executed you  will  find  the  errors/result in  here.
  91.                         NOTE: If acme_RC is negative  it  means that  acme_RC2
  92.                               contains a pointer to an error string instead of
  93.                               an error number.
  94.  
  95.                 acme_IO -- If you execute a script using this  method  you can
  96.                         pass a pointer to the IO channel ARexx must  use here.
  97.                         This IO channel will be  closed  automatically for you
  98.                         after the command executed.
  99.  
  100.                 As errors are reported  in  acme_RC and  acme_RC2 this  method
  101.                 has no specific return code.
  102.  
  103.     CHANGED METHODS
  104.         None.
  105.  
  106. arexxclass/Attributes                                    arexxclass/Attributes
  107.  
  108.     NAME
  109.         AC_HostName -- ( STRPTR )
  110.  
  111.     FUNCTION
  112.         To supply  the  object  with  a base name it must use for it's message
  113.         port. Internally this base name is converted to find a unique version.
  114.         The class  does  this  by  appending a number to the base name. If you
  115.         need to  know the real host name simply OM_GET it after the object has
  116.         been created.
  117.  
  118.         If, for  example,  you  provide  a  base  name of "FOO" the class will
  119.         internally try  to  create a host port with the names "FOO.1", "FOO.2"
  120.         ... "FOO.99".  When  none of these names is unique the object creation
  121.         fails.
  122.  
  123.         This attribute must be valid or the object will fail to create.
  124.  
  125.         Default is NULL. Applicability is (IG).
  126.  
  127.     NAME
  128.         AC_FileExtention -- ( STRPTR )
  129.  
  130.     FUNCTION
  131.         To establish the file extention you will be using for your host.  This
  132.         file extention is used by the ARexx server to determine  what  file it
  133.         should try to open if the original file name did not open.
  134.  
  135.         Default = "rexx". Applicability is (I)
  136.  
  137.     NAME
  138.         AC_CommandList -- ( REXXCOMMAND * )
  139.  
  140.     FUNCTION
  141.         To provide  your  host  with  it's  commands. The data must be a valid
  142.         pointer to an array of the following structures:
  143.  
  144.         typedef struct {
  145.                 UBYTE           *rc_Name;
  146.                 UBYTE           *rc_ArgTemplate;
  147.                 VOID           (*rc_Func)( REXXARGS *, struct RexxMsg * );
  148.         } REXXCOMMAND;
  149.  
  150.         rc_Name -- This must be a pointer to the command name.  Although there
  151.                 are no restrictions it is advisable that commands are in upper
  152.                 case characters.
  153.  
  154.         rc_ArgTemplate -- If your command expects arguments this must point to
  155.                 a  standard  AmigaDOS argument template string. Internally the
  156.                 class will use  ReadArgs()  to  parse  the  arguments  for the
  157.                 command.  If  your  command does not expec s arguments you can
  158.                 set this to NULL.
  159.  
  160.         rc_Func -- This must be a pointer to your command routine. The routine
  161.                 will get called as follows with the arguments on the stack:
  162.  
  163.                 VOID command_func( REXXARGS *ra, struct RexxMsg *rxm );
  164.  
  165.                 ra -- This will be a pointer to the following structure:
  166.  
  167.                 typedef struct {
  168.                         ULONG   *ra_ArgList;
  169.                         LONG     ra_RC;
  170.                         LONG     ra_RC2;
  171.                         UBYTE   *ra_Result;
  172.                 } REXXARGS;
  173.  
  174.                 ra_ArgList -- This will point to an array of ULONGs containing
  175.                         the result of the ReadArgs() parse.  This  may also be
  176.                         NULL in which case  the  command  does  not expect any
  177.                         arguments.
  178.  
  179.                 ra_RC -- In here you can store the primary error (if any).
  180.  
  181.                 ra_RC2 -- In here you can store the secundary error.   If  you
  182.                         wish to  make  this  a  descriptive  error  string you
  183.                         should provide a negative primary error code I.E.:
  184.  
  185.                         VOID command( REXXARGS *ra, struct RexxMsg *rxm )
  186.                         {
  187.                                 /* Do your stuff... */
  188.  
  189.                                 ra->ra_RC  = -RC_ERROR;
  190.                                 ra->ra_RC2 = (LONG)"Out of memory!";
  191.                         }
  192.  
  193.                         If you want to provide a descriptive  error  code  you
  194.                         should provide a positive primary error code I.E.:
  195.  
  196.                         VOID command( REXXARGS *ra, struct RexxMsg *rxm )
  197.                         {
  198.                                 /* Do your stuff... */
  199.  
  200.                                 ra->ra_RC  = RC_ERROR;
  201.                                 ra->ra_RC2 = IoErr();
  202.                         }
  203.  
  204.                 ra_Result -- If your command has a result  of  some  kind  you
  205.                         should store a pointer to that result in here.  Please
  206.                         note that this is expected to  be  a  string so if you
  207.                         wish to return a  numeric  result  you  will  have  to
  208.                         convert it to a string first I.E.:
  209.  
  210.                         UBYTE                   buf[ 16 ];
  211.  
  212.                         VOID command( REXXARGS *ra, struct RexxMsg *rxm )
  213.                         {
  214.                                 UWORD                   number;
  215.  
  216.                                 /* Do your stuff... */
  217.  
  218.                                 if ( rxm && rxm->rm_Action & RXFF_RESULT ) {
  219.                                         sprintf( buf, "%ld", number );
  220.                                         ra->ra_Result = buf;
  221.                                 }
  222.                         }
  223.  
  224.         rxm -- This points to the RexxMessage structure of your command.  You
  225.                may  use this to setup  ARexx  variables  or  stem  variables.
  226.                Please note that this may be NULL.
  227.  
  228.         The array must be terminated with a NULL rc_Name field.
  229.  
  230.         This tag must be valid or the object will fail to create.
  231.  
  232.         Default is NULL. Applicability is (I).
  233.  
  234.     NAME
  235.         AC_ErrorCode -- ( ULONG * )
  236.  
  237.     FUNCTION
  238.         To provide storage space for the class to  store a  descriptive  error
  239.         code if the object creation fails.  If the object  creation  fails the
  240.         storage space provided can contain any of the following error codes:
  241.  
  242.         RXERR_NO_COMMAND_LIST     -- No command list was provided.
  243.         RXERR_NO_PORT_NAME        -- No host base name was provided.
  244.         RXERR_PORT_ALREADY_EXISTS -- The  class  was unable to create a unique
  245.                                      name of the base name you provided.
  246.         RXERR_OUT_OF_MEMORY       -- Not enough free memory.
  247.  
  248.         Default is NULL. Applicability is (I).
  249.  
  250.    SEE ALSO
  251.         AC_HostName, AC_CommandList
  252.  
  253.    NAME
  254.         AC_RexxHostMask -- ( ULONG * )
  255.  
  256.    FUNCTION
  257.         To obtain the host port signal mask.
  258.  
  259.         Example:
  260.  
  261.         Object *AO_Rexx;
  262.         ULONG   mask, sigrec;
  263.  
  264.         GetAttr( AC_RexxHostMask, AO_Rexx, &mask );
  265.  
  266.         do {
  267.                 sigrec = Wait( mask );
  268.  
  269.                 if ( sigrec & mask )
  270.                         DoMethod( AO_Rexx, ACM_HANDLE_EVENT );
  271.         } while ( ... );
  272.  
  273.         Applicability is (G)
  274.